home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 098 / ccheck.arc / CCHECK.DOC < prev    next >
Encoding:
Text File  |  1985-06-23  |  8.1 KB  |  199 lines
  1.  
  2.  
  3.  
  4.      ccheck            MS-DOS 2.x              ccheck
  5.  
  6.  
  7.  
  8.      NAME
  9.       ccheck - C program checker
  10.  
  11.      SYNOPSIS
  12.       ccheck [-q] [-v] [files ...]
  13.  
  14.      EXAMPLE
  15.            ccheck foo.c >foo.err
  16.  
  17.      DESCRIPTION
  18.       Ccheck checks    C programs for correctly matching brackets of
  19.       all kinds, including quotes and comment brackets, checks
  20.       that the indentation of matching brackets also matches, and
  21.       checks for symptoms of 3 kinds of errors that    the C compiler
  22.       allows without warning: "dangling else" errors where an else
  23.       is bound to the wrong    preceding if, nested comments, where
  24.       the first close-comment bracket prematurely ends the outer
  25.       comment, and the use of assignment ('=') where equality-test
  26.       ('==') was meant.  It    is meant to be run as a    pre-check on C
  27.       programs before calling the compiler.     Its virtues are that
  28.       it allows you    to weed    out some trivial syntactic errors
  29.       faster; for the errors it detects it produces    better error
  30.       messages than    the compiler; and it detects the errors
  31.       mentioned above that the compiler ignores.
  32.  
  33.       The indentation rules    it applies are that the    indentation of
  34.       the first non-white character    on the line holding an opener
  35.       should match that on the line    holding    the matching closer.
  36.       These    rules are fairly weak (e.g. they are compatible    with
  37.       but do not enforce the Ingres    format standard), though they
  38.       may still conflict with your own habits.  The    -q (quiet)
  39.       option suppresses messages classed as    warnings, which
  40.       includes those about mismatched indentations.     The -v
  41.       (verbose) option prints more information -- it shows what is
  42.       on its internal stack    at the time an error is    detected.  It
  43.       is probably only of real use for debugging ccheck itself.
  44.  
  45.       The distinction between warnings and errors is somewhat
  46.       arbitrary.  Because C    allows certain errors it would be
  47.       inappropriate    here to    make the distinction between
  48.       compilable and non-compilable    programs.  Basically only
  49.       indentation mismatches are warnings, and the symptoms    of
  50.       dangling elses or using assignment ('=') instead of equality
  51.       ('==') are treated as    errors.     The program will always print
  52.       some message if you have an error involving mismatched
  53.       brackets of some kind, and will pass any legal program if
  54.       its indentation is also correct, unless '=' is used in the
  55.       top level of a condition expression.    For cases in between
  56.       it tries hard    but may    make mistakes, though if you are
  57.       aiming for a properly    indented program you can be sure that
  58.       an error means that something    is wrong.
  59.  
  60.  
  61.  
  62.  
  63.      Page 1                          (printed 1/9/83)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      ccheck            MSs-DOS 2.x              ccheck
  71.  
  72.  
  73.  
  74.       When it detects signs    of a bracket mismatch it makes a
  75.       decision on the spot about the most likely underlying    cause.
  76.       It does not wait for more evidence to    disambiguate this, so
  77.       on the occasions it is wrong,    not only are the messages
  78.       inappropriate    to some    degree,    but several messages may be
  79.       produced concerning what is really a single (unrecognized)
  80.       error.  The most common example of this is if    you have the
  81.       wrong    indent on a closing brace such that it matches an
  82.       earlier opening brace, ccheck    assumes    first that there is a
  83.       missing closing brace, and then when it finds    the second
  84.       closing brace    that this has no matching opening brace    (this
  85.       having been already wrongly accounted    for).  The summary it
  86.       gives    at the end tells you whether there was really a    net
  87.       imbalance of brackets, which may help    sort out these cases.
  88.  
  89.       Ccheck was written as    a result of the    following
  90.       observations.
  91.        1)  In Unix,    modularity suggests that it is appropriate to
  92.       have different programs with different special expertise
  93.       where    other systems would cram them all into one program.
  94.       Thus lint incorporates special knowledge about type-checking
  95.       and portability considerations that would be inappropriate
  96.       in a compiler.  Ccheck like lint takes advantage of the fact
  97.       that since it    is not the compiler it can be wrong some of
  98.       the time without preventing anyone from doing    anything.
  99.        2)  C has, in my opinion, some bad choices in its syntax
  100.       that cause frequent errors by    users.    It turns out, though,
  101.       that these can largely be checked for    cheaply, which
  102.       alleviates the original poor design choice.  These are:
  103.            a) Not supporting nested    comments (nor warning about
  104.       them in the compiler).
  105.            b) Not having an    "endif"    (or "fi") closer to terminate
  106.       if statements, thus leaving users open to the    dangling else
  107.       problem.  (This is the problem that if you have nested if
  108.       statements the following else    will get bound to the nearest
  109.       preceding one, which is not always the intuitively
  110.       reasonable one.)  This is especially troublesome, as it
  111.       means    among other things that    if you modify a    program    by
  112.       adding an else clause    to an existing if statement, you may
  113.       have to modify (by adding braces) not    the if statement to
  114.       which    you are    attaching the else, but    a nested if statement
  115.       acting as its    "then" clause.
  116.            c) The use of '=' for assignment, following Fortran's
  117.       bad usage.  It seems to be the case that both    '=' and    '=='
  118.       get seen and mentally    read as    "equals" so that it is hard to
  119.       spot if you write '='    for '==' in conditionals, an error
  120.       that may happen either because of the    language-promoted
  121.       confusion itself, or because of a typing slip    (which is then
  122.       hard to spot).
  123.        3) The C compiler produces outstandingly unhelpful error
  124.       messages as a    rule, from the point of    view of    a user who
  125.       wants    to make    corrections as fast as possible.  Once past
  126.  
  127.  
  128.  
  129.      Page 2                          (printed 1/9/83)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      ccheck            MS-DOS 2.x              ccheck
  137.  
  138.  
  139.  
  140.       the beginner stage however, a    user can usually do all    right
  141.       by ignoring the text of the error message, which almost
  142.       never    tells her/him what to correct, and attending to    the
  143.       line-number:    generally when your attention is directed to
  144.       only a line or two you can tell what is wrong.  This breaks
  145.       down when the    compiler fails to generate anything like the
  146.       helpful line number.    This is    usually    however    in cases of
  147.       failure to match brackets of some sort -- something which is
  148.       easy for another program to check.  Furthermore attending to
  149.       the user's indentation usually allows    accurate diagnoses and
  150.       helpful messages to be generated in just these cases.
  151.  
  152.       Ccheck, then,    attempts to address these points largely by
  153.       checking bracket matches and using indentation to guess what
  154.       the real problem was -- whether a missing opener, a missing
  155.       closer, wrong    indentation, or    some other mistake such    as a
  156.       spurious character.  Like the    compiler, it has only a    fair
  157.       chance of recovering after an    error and commenting
  158.       intelligently    on the remaining code.    However    its relatively
  159.       fast running time means that correcting only the first error
  160.       in each cycle    is not too time    consuming.
  161.  
  162.      BUGS
  163.       It inflicts its own idea of good indentation,    which neither
  164.       matches a recognized standard    exactly    nor your own
  165.       practices.  It can generate several error descriptions where
  166.       there    is only    one error -- one that it does not describe.
  167.  
  168.       It does not deal with    the preprocessor intelligently.     There
  169.       are two kinds    of case    to note:
  170.        1) defines may themselves not be good C e.g.
  171.            #define ctrl(letter) ('letter' &    077)
  172.       will work ok in the program but will draw "bad character
  173.       constant" from ccheck. Similarly, though more    questionable,
  174.       you might define your    own opener and closer e.g.
  175.            #define then {
  176.            #define endif }
  177.        2)  Some uses of #ifdef will    confuse    ccheck,    for instance
  178.       if alternative if-condition lines are    given, controlled by
  179.       #ifdef ... #else ccheck will see them    both.  Similarly using
  180.       "#ifdef comment" to comment out parts    of the text in order
  181.       to overcome the lack of nested comments in C will draw fire
  182.       if the commented out section is not legal C.
  183.  
  184.       Do-while loops within    an "if"    clause result in the "if"
  185.       being    forgotten.
  186.  
  187.      AUTHOR
  188.       Steve    Draper
  189.  
  190.      PROVIDER
  191.       Jeff Martin
  192.  
  193.  
  194.  
  195.      Page 3                          (printed 1/9/83)
  196.  
  197.  
  198.  
  199.